/*
 * Copyright 2002-2012 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.bind;

import org.springframework.beans.MutablePropertyValues;
import org.springframework.beans.PropertyValue;
import org.springframework.validation.DataBinder;
import org.springframework.web.multipart.MultipartFile;

import java.lang.reflect.Array;
import java.util.List;
import java.util.Map;

/**
 * Special {@link DataBinder} for data binding from web request parameters
 * to JavaBean objects. Designed for web environments, but not dependent on
 * the Servlet API; serves as base class for more specific DataBinder variants,
 * such as {@link org.springframework.web.bind.ServletRequestDataBinder}.
 *
 * <p>Includes support for field markers which address a common problem with
 * HTML checkboxes and select options: detecting that a field was part of
 * the form, but did not generate a request parameter because it was empty.
 * A field marker allows to detect that state and reset the corresponding
 * bean property accordingly. Default values, for parameters that are otherwise
 * not present, can specify a value for the field other then empty.
 *
 * @author Juergen Hoeller
 * @author Scott Andrews
 * @see #registerCustomEditor
 * @see #setAllowedFields
 * @see #setRequiredFields
 * @see #setFieldMarkerPrefix
 * @see #setFieldDefaultPrefix
 * @see ServletRequestDataBinder
 * @since 1.2
 */
public class WebDataBinder extends DataBinder {

    /**
     * Default prefix that field marker parameters start with, followed by the field
     * name: e.g. "_subscribeToNewsletter" for a field "subscribeToNewsletter".
     * <p>Such a marker parameter indicates that the field was visible, that is,
     * existed in the form that caused the submission. If no corresponding field
     * value parameter was found, the field will be reset. The value of the field
     * marker parameter does not matter in this case; an arbitrary value can be used.
     * This is particularly useful for HTML checkboxes and select options.
     *
     * @see #setFieldMarkerPrefix
     */
    public static final String DEFAULT_FIELD_MARKER_PREFIX = "_";

    /**
     * Default prefix that field default parameters start with, followed by the field
     * name: e.g. "!subscribeToNewsletter" for a field "subscribeToNewsletter".
     * <p>Default parameters differ from field markers in that they provide a default
     * value instead of an empty value.
     *
     * @see #setFieldDefaultPrefix
     */
    public static final String DEFAULT_FIELD_DEFAULT_PREFIX = "!";

    private String fieldMarkerPrefix = DEFAULT_FIELD_MARKER_PREFIX;

    private String fieldDefaultPrefix = DEFAULT_FIELD_DEFAULT_PREFIX;

    private boolean bindEmptyMultipartFiles = true;


    /**
     * Create a new WebDataBinder instance, with default object name.
     *
     * @param target the target object to bind onto (or {@code null}
     *               if the binder is just used to convert a plain parameter value)
     * @see #DEFAULT_OBJECT_NAME
     */
    public WebDataBinder(Object target) {
        super(target);
    }

    /**
     * Create a new WebDataBinder instance.
     *
     * @param target     the target object to bind onto (or {@code null}
     *                   if the binder is just used to convert a plain parameter value)
     * @param objectName the name of the target object
     */
    public WebDataBinder(Object target, String objectName) {
        super(target, objectName);
    }


    /**
     * Specify a prefix that can be used for parameters that mark potentially
     * empty fields, having "prefix + field" as name. Such a marker parameter is
     * checked by existence: You can send any value for it, for example "visible".
     * This is particularly useful for HTML checkboxes and select options.
     * <p>Default is "_", for "_FIELD" parameters (e.g. "_subscribeToNewsletter").
     * Set this to null if you want to turn off the empty field check completely.
     * <p>HTML checkboxes only send a value when they're checked, so it is not
     * possible to detect that a formerly checked box has just been unchecked,
     * at least not with standard HTML means.
     * <p>One way to address this is to look for a checkbox parameter value if
     * you know that the checkbox has been visible in the form, resetting the
     * checkbox if no value found. In Spring web MVC, this typically happens
     * in a custom {@code onBind} implementation.
     * <p>This auto-reset mechanism addresses this deficiency, provided
     * that a marker parameter is sent for each checkbox field, like
     * "_subscribeToNewsletter" for a "subscribeToNewsletter" field.
     * As the marker parameter is sent in any case, the data binder can
     * detect an empty field and automatically reset its value.
     *
     * @see #DEFAULT_FIELD_MARKER_PREFIX
     * @see org.springframework.web.servlet.mvc.BaseCommandController#onBind
     */
    public void setFieldMarkerPrefix(String fieldMarkerPrefix) {
        this.fieldMarkerPrefix = fieldMarkerPrefix;
    }

    /**
     * Return the prefix for parameters that mark potentially empty fields.
     */
    public String getFieldMarkerPrefix() {
        return this.fieldMarkerPrefix;
    }

    /**
     * Specify a prefix that can be used for parameters that indicate default
     * value fields, having "prefix + field" as name. The value of the default
     * field is used when the field is not provided.
     * <p>Default is "!", for "!FIELD" parameters (e.g. "!subscribeToNewsletter").
     * Set this to null if you want to turn off the field defaults completely.
     * <p>HTML checkboxes only send a value when they're checked, so it is not
     * possible to detect that a formerly checked box has just been unchecked,
     * at least not with standard HTML means.  A default field is especially
     * useful when a checkbox represents a non-boolean value.
     * <p>The presence of a default parameter preempts the behavior of a field
     * marker for the given field.
     *
     * @see #DEFAULT_FIELD_DEFAULT_PREFIX
     * @see org.springframework.web.servlet.mvc.BaseCommandController#onBind
     */
    public void setFieldDefaultPrefix(String fieldDefaultPrefix) {
        this.fieldDefaultPrefix = fieldDefaultPrefix;
    }

    /**
     * Return the prefix for parameters that mark default fields.
     */
    public String getFieldDefaultPrefix() {
        return this.fieldDefaultPrefix;
    }

    /**
     * Set whether to bind empty MultipartFile parameters. Default is "true".
     * <p>Turn this off if you want to keep an already bound MultipartFile
     * when the user resubmits the form without choosing a different file.
     * Else, the already bound MultipartFile will be replaced by an empty
     * MultipartFile holder.
     *
     * @see org.springframework.web.multipart.MultipartFile
     */
    public void setBindEmptyMultipartFiles(boolean bindEmptyMultipartFiles) {
        this.bindEmptyMultipartFiles = bindEmptyMultipartFiles;
    }

    /**
     * Return whether to bind empty MultipartFile parameters.
     */
    public boolean isBindEmptyMultipartFiles() {
        return this.bindEmptyMultipartFiles;
    }


    /**
     * This implementation performs a field default and marker check
     * before delegating to the superclass binding process.
     *
     * @see #checkFieldDefaults
     * @see #checkFieldMarkers
     */
    @Override
    protected void doBind(MutablePropertyValues mpvs) {
        checkFieldDefaults(mpvs);
        checkFieldMarkers(mpvs);
        super.doBind(mpvs);
    }

    /**
     * Check the given property values for field defaults,
     * i.e. for fields that start with the field default prefix.
     * <p>The existence of a field defaults indicates that the specified
     * value should be used if the field is otherwise not present.
     *
     * @param mpvs the property values to be bound (can be modified)
     * @see #getFieldDefaultPrefix
     */
    protected void checkFieldDefaults(MutablePropertyValues mpvs) {
        if (getFieldDefaultPrefix() != null) {
            String fieldDefaultPrefix = getFieldDefaultPrefix();
            PropertyValue[] pvArray = mpvs.getPropertyValues();
            for (PropertyValue pv : pvArray) {
                if (pv.getName().startsWith(fieldDefaultPrefix)) {
                    String field = pv.getName().substring(fieldDefaultPrefix.length());
                    if (getPropertyAccessor().isWritableProperty(field) && !mpvs.contains(field)) {
                        mpvs.add(field, pv.getValue());
                    }
                    mpvs.removePropertyValue(pv);
                }
            }
        }
    }

    /**
     * Check the given property values for field markers,
     * i.e. for fields that start with the field marker prefix.
     * <p>The existence of a field marker indicates that the specified
     * field existed in the form. If the property values do not contain
     * a corresponding field value, the field will be considered as empty
     * and will be reset appropriately.
     *
     * @param mpvs the property values to be bound (can be modified)
     * @see #getFieldMarkerPrefix
     * @see #getEmptyValue(String, Class)
     */
    protected void checkFieldMarkers(MutablePropertyValues mpvs) {
        if (getFieldMarkerPrefix() != null) {
            String fieldMarkerPrefix = getFieldMarkerPrefix();
            PropertyValue[] pvArray = mpvs.getPropertyValues();
            for (PropertyValue pv : pvArray) {
                if (pv.getName().startsWith(fieldMarkerPrefix)) {
                    String field = pv.getName().substring(fieldMarkerPrefix.length());
                    if (getPropertyAccessor().isWritableProperty(field) && !mpvs.contains(field)) {
                        Class fieldType = getPropertyAccessor().getPropertyType(field);
                        mpvs.add(field, getEmptyValue(field, fieldType));
                    }
                    mpvs.removePropertyValue(pv);
                }
            }
        }
    }

    /**
     * Determine an empty value for the specified field.
     * <p>Default implementation returns {@code Boolean.FALSE}
     * for boolean fields and an empty array of array types.
     * Else, {@code null} is used as default.
     *
     * @param field     the name of the field
     * @param fieldType the type of the field
     * @return the empty value (for most fields: null)
     */
    protected Object getEmptyValue(String field, Class fieldType) {
        if (fieldType != null && boolean.class.equals(fieldType) || Boolean.class.equals(fieldType)) {
            // Special handling of boolean property.
            return Boolean.FALSE;
        } else if (fieldType != null && fieldType.isArray()) {
            // Special handling of array property.
            return Array.newInstance(fieldType.getComponentType(), 0);
        } else {
            // Default value: try null.
            return null;
        }
    }


    /**
     * Bind the multipart files contained in the given request, if any
     * (in case of a multipart request).
     * <p>Multipart files will only be added to the property values if they
     * are not empty or if we're configured to bind empty multipart files too.
     *
     * @param multipartFiles Map of field name String to MultipartFile object
     * @param mpvs           the property values to be bound (can be modified)
     * @see org.springframework.web.multipart.MultipartFile
     * @see #setBindEmptyMultipartFiles
     * @deprecated as of Spring 3.0, in favor of {@link #bindMultipart} which binds
     * all multipart files, even if more than one sent for the same name
     */
    @Deprecated
    protected void bindMultipartFiles(Map<String, MultipartFile> multipartFiles, MutablePropertyValues mpvs) {
        for (Map.Entry<String, MultipartFile> entry : multipartFiles.entrySet()) {
            String key = entry.getKey();
            MultipartFile value = entry.getValue();
            if (isBindEmptyMultipartFiles() || !value.isEmpty()) {
                mpvs.add(key, value);
            }
        }
    }

    /**
     * Bind all multipart files contained in the given request, if any
     * (in case of a multipart request).
     * <p>Multipart files will only be added to the property values if they
     * are not empty or if we're configured to bind empty multipart files too.
     *
     * @param multipartFiles Map of field name String to MultipartFile object
     * @param mpvs           the property values to be bound (can be modified)
     * @see org.springframework.web.multipart.MultipartFile
     * @see #setBindEmptyMultipartFiles
     */
    protected void bindMultipart(Map<String, List<MultipartFile>> multipartFiles, MutablePropertyValues mpvs) {
        for (Map.Entry<String, List<MultipartFile>> entry : multipartFiles.entrySet()) {
            String key = entry.getKey();
            List<MultipartFile> values = entry.getValue();
            if (values.size() == 1) {
                MultipartFile value = values.get(0);
                if (isBindEmptyMultipartFiles() || !value.isEmpty()) {
                    mpvs.add(key, value);
                }
            } else {
                mpvs.add(key, values);
            }
        }
    }

}
